17.5.7.1 Data Type Formats

Integers are stored in either of two ways, depending on their magnitude. Integers less than one million in absolute value are stored as standard Lisp integers. This is the only storage format for Calc data objects which is not a Lisp list.

Large integers are stored as lists of the form ‘(bigpos d0 d1 d2 …)’ for sufficiently large positive integers (where “sufficiently large” depends on the machine), or ‘(bigneg d0 d1 d2 …)’ for negative integers. Each d is a base-‘10^n’ “digit” (where again, ‘n’ depends on the machine), a Lisp integer from 0 to 99…9. The least significant digit is d0; the last digit, dn, which is always nonzero, is the most significant digit. For example, the integer -12345678 might be stored as ‘(bigneg 678 345 12)’.

The distinction between small and large integers is entirely hidden from the user. In defmath definitions, the Lisp predicate integerp returns true for either kind of integer, and in general both big and small integers are accepted anywhere the word “integer” is used in this manual. If the distinction must be made, native Lisp integers are called fixnums and large integers are called bignums.

Fractions are stored as a list of the form, ‘(frac n d)’ where n is an integer (big or small) numerator, d is an integer denominator greater than one, and n and d are relatively prime. Note that fractions where d is one are automatically converted to plain integers by all math routines; fractions where d is negative are normalized by negating the numerator and denominator.

Floating-point numbers are stored in the form, ‘(float mant exp)’, where mant (the “mantissa”) is an integer less than ‘10^p’ in absolute value (p represents the current precision), and exp (the “exponent”) is a fixnum. The value of the float is ‘mant * 10^exp’. For example, the number -3.14 is stored as ‘(float -314 -2) = -314*10^-2’. Other constraints are that the number 0.0 is always stored as ‘(float 0 0)’, and, except for the 0.0 case, the rightmost base-10 digit of mant is always nonzero. (If the rightmost digit is zero, the number is rearranged by dividing mant by ten and incrementing exp.)

Rectangular complex numbers are stored in the form ‘(cplx re im)’, where re and im are each real numbers, either integers, fractions, or floats. The value is ‘re + imi’. The im part is nonzero; complex numbers with zero imaginary components are converted to real numbers automatically.

Polar complex numbers are stored in the form ‘(polar r theta)’, where r is a positive real value and theta is a real value or HMS form representing an angle. This angle is usually normalized to lie in the interval ‘(-180 .. 180)’ degrees, or ‘(-pi .. pi)’ radians, according to the current angular mode. If the angle is 0 the value is converted to a real number automatically. (If the angle is 180 degrees, the value is usually also converted to a negative real number.)

Hours-minutes-seconds forms are stored as ‘(hms h m s)’, where h is an integer or an integer-valued float (i.e., a float with ‘exp >= 0’), m is an integer or integer-valued float in the range ‘[0 .. 60)’, and s is any real number in the range ‘[0 .. 60)’.

Date forms are stored as ‘(date n)’, where n is a real number that counts days since midnight on the morning of January 1, 1 AD. If n is an integer, this is a pure date form. If n is a fraction or float, this is a date/time form.

Modulo forms are stored as ‘(mod n m)’, where m is a positive real number or HMS form, and n is a real number or HMS form in the range ‘[0 .. m)’.

Error forms are stored as ‘(sdev x sigma)’, where x is the mean value and sigma is the standard deviation. Each component is either a number, an HMS form, or a symbolic object (a variable or function call). If sigma is zero, the value is converted to a plain real number. If sigma is negative or complex, it is automatically normalized to be a positive real.

Interval forms are stored as ‘(intv mask lo hi)’, where mask is one of the integers 0, 1, 2, or 3, and lo and hi are real numbers, HMS forms, or symbolic objects. The mask is a binary integer where 1 represents the fact that the interval is closed on the high end, and 2 represents the fact that it is closed on the low end. (Thus 3 represents a fully closed interval.) The interval ‘(intv 3 x x)’ is converted to the plain number x; intervals ‘(intv mask x x)’ for any other mask represent empty intervals. If hi is less than lo, the interval is converted to a standard empty interval by replacing hi with lo.

Vectors are stored as ‘(vec v1 v2 …)’, where v1 is the first element of the vector, v2 is the second, and so on. An empty vector is stored as ‘(vec)’. A matrix is simply a vector where all v’s are themselves vectors of equal lengths. Note that Calc vectors are unrelated to the Emacs Lisp “vector” type, which is generally unused by Calc data structures.

Variables are stored as ‘(var name sym)’, where name is a Lisp symbol whose print name is used as the visible name of the variable, and sym is a Lisp symbol in which the variable’s value is actually stored. Thus, ‘(var pi var-pi)’ represents the special constant ‘pi’. Almost always, the form is ‘(var v var-v)’. If the variable name was entered with # signs (which are converted to hyphens internally), the form is ‘(var u v)’, where u is a symbol whose name contains # characters, and v is a symbol that contains - characters instead. The value of a variable is the Calc object stored in its sym symbol’s value cell. If the symbol’s value cell is void or if it contains nil, the variable has no value. Special constants have the form ‘(special-const value)’ stored in their value cell, where value is a formula which is evaluated when the constant’s value is requested. Variables which represent units are not stored in any special way; they are units only because their names appear in the units table. If the value cell contains a string, it is parsed to get the variable’s value when the variable is used.

A Lisp list with any other symbol as the first element is a function call. The symbols +, -, *, /, %, ^, and | represent special binary operators; these lists are always of the form ‘(op lhs rhs)’ where lhs is the sub-formula on the lefthand side and rhs is the sub-formula on the right. The symbol neg represents unary negation; this list is always of the form ‘(neg arg)’. Any other symbol func represents a function that would be displayed in function-call notation; the symbol func is in general always of the form ‘calcFunc-name’. The function cell of the symbol func should contain a Lisp function for evaluating a call to func. This function is passed the remaining elements of the list (themselves already evaluated) as arguments; such functions should return nil or call reject-arg to signify that they should be left in symbolic form, or they should return a Calc object which represents their value, or a list of such objects if they wish to return multiple values. (The latter case is allowed only for functions which are the outer-level call in an expression whose value is about to be pushed on the stack; this feature is considered obsolete and is not used by any built-in Calc functions.)